.\"
.\"
.TH MAT 1 "Nov 9, 2014" "Memory Analysis Tool"
.SH NAME
mat - Memory Analysis Tool
.SH SYNOPSIS
.B mat
[ -i ] [ -o
.I directory
] [ -t
.I templates
] [ -c
.I config-dir
]
.I command
.br
.SH DESCRIPTION
\fImat\fR is a memory analysis tool intended to help understand what areas of a program
use the most memory.  The tool works with a small shared library
.I libgpmat.so
that must be loaded by the program to analyze. The shared library catches a number of
memory allocation operations such as
.BR malloc ,
.B realloc
and
.B free
and informs
.I mat
about the memory allocation.  It then writes or sends probe events which contain
enough information for
.I mat
to tell what, when, where and by whom the memory allocation was done.
.\"
.PP
The memory analysis can be done when the program has finished or while the program is still running
or debugged through
.BR gdb (1).
In the first case, the
.I libgpmat.so
library will have to write the information to a file that is later read by
.I mat
for analysis.  In the second case, the
.I libgpmat.so
library will send the information to the
.I mat
server through a TCP/IP connection.  The
.I mat
server and the
.I libgpmat.so
client can run on different hosts and they can use different architectures.
.\"
.PP
The
.I mat
tool offers a number of commands to analyze the memory used.
.\"
.PP
.\"
.SH OPTIONS
The following options are recognized by \fImat\fR:
.TP 5
.B -i
Enable the interactive mode.
.TP 5
.B -b [ip:]port
.br
Define the TCP/IP port and local address to bind.
.TP 5
.B -nw
.br
Disable the graphical mode.
.TP 5
.B -ns
.br
Disable the automatic symbols loading.
.\"
.SH SETUP
.\"
Before starting the program to analyze, two environment variables must be set.
.PP
The first environment variable to set is
.I LD_PRELOAD
which tells the linker to force the loading of a shared library at the startup of
a program.  This variable should indicate the absolute path where the
.I libgpmat.so
shared library is installed on your system.
.PP
.RS 2
export LD_PRELOAD=/usr/lib/libgpmat.so
.RE
.\"
.PP
The second environment variable is used by the
.I libgpmat.so
shared library to configure the destination of probe events that the library generates.
The probe events can be written to a file that is later read by
.I mat
for analysis.  The
.I MAT_SERVER
environment variable indicates the path of the file where the probe events will be written
during execution.
.PP
.RS 2
export MAT_SERVER=file://my-record
.RE
.\"
.PP
The probe events can be redirected to a TCP/IP connection that
.I mat
is listening.  In that case, the
.I MAT_SERVER
environment variable indicates the TCP/IP host and port.  The
.I mat
tool must be started before the program under analysis.
.PP
.RS 2
export MAT_SERVER=tcp://192.168.0.12:4096
.RE
.\"
.SH COMMANDS
The interactive mode of
.I mat
provides the following commands:
.\"
.TP 5
sizes
.\"
The
.B sizes
command reports the different memory slot sizes that are allocated by the program.
.\"
.TP 5
frames level
.\"
The
.B frames
command reports the functions that have made a memory allocation directly or indirectly.
.\"
.TP 5
slots [filter]
.\"
The
.B slots
command reports the memory slots that are allocated and that match the filter expression.
.\"
.TP 5
symbol path
.\"
The
.B symbol
command loads the symbol information from the given path.  The program should be compiled
with
.B -g
to obtain information about source file and line number.
.\"
.TP 5
threads
.\"
The
.B threads
command reports the list of threads with the memory that they allocated.
.\"
.TP 5
exit
The
.B exit
command terminates the analysis.
.\"
.TP 5
open mat-file
The
.B open
command loads the file generated by
.I libgpmat.so
.\"
.SH SEE ALSO
\fIgcc(1)\fR, \fIgdb(1)\fR, \fIld.so(8)\fR, \fIvalgrind(1)\fR
.\"
.SH AUTHOR
Written by Stephane Carrez.
.\"
